=begin pod :kind("Language") :subkind("Language") :category("migration")

=TITLE Ruby to Raku - nutshell

=SUBTITLE Learning Raku from Ruby, in a nutshell: what do I already know?

This page attempts to index the high-level differences in syntax and semantics
between Ruby and Raku. Whatever works in Ruby and must be written differently
in Raku should be listed here (whereas many Raku features and idioms won't
be).

Hence this should not be mistaken for a beginner tutorial or overview of Raku; it is intended as a technical reference for Raku learners with a strong
Ruby background.


=head1 Basic syntax

=head2 Statement ending semicolons

Ruby detects the end of most statements with a newline (and a few exceptions),
as long as the expression is complete. It is common break up a long expression
by leaving an operator dangling at the end of a line to ensure that the parsing
will continue:

=for code :lang<ruby>
foo +     # In Ruby a trailing operator means parsing should continue
  bar +
  baz

In Raku you must explicitly terminate statements with a C<;>, which allows
for better feedback and more flexibility in breaking up long lines. Two
exceptions not needing an explicit C<;> are the last statement in a block, and
after the closing curly brace of the block itself (if there is nothing else on
that line):

    my $x;
    ...;
    if 5 < $x < 10 {
      say "Yep!";
      $x = 17         # No ; required before closing }
    }                 # No ; required after closing } because of the newline
    say "Done!";      # The ; is not required here if nothing follows

=head2 Whitespace

Ruby allows a surprising amount of flexibility in the use of whitespace,
even with strict mode and warnings turned on:

=for code :lang<ruby>
# unidiomatic but valid Ruby
puts"Hello "+
(people [ i]
    . name
    ) . upcase+"!"if$greeted[i]<1

Raku also endorses programmer freedom and creativity, but balanced syntactic
flexibility against its design goal of having a consistent, deterministic,
extensible grammar that supports single-pass parsing and helpful error
messages, integrates features like custom operators cleanly, and doesn't lead
programmers to accidentally misstate their intent. Also, the practice of "code
golf" is slightly de-emphasized; Raku is designed to be more concise in
concepts than in keystrokes.

As a result, there are various places in the syntax where whitespace is
optional in Ruby, but is either mandatory or forbidden in Raku. Many of those
restrictions are unlikely to concern much real-life Perl code (e.g. whitespace
being disallowed between an array variable and its square brackets), but there
are a few that will unfortunately conflict with some Ruby hackers' habitual
coding styles:

=begin item
I<No space allowed before the opening parenthesis of an argument list.>

=begin code :skip-test<illustrates error>
foo (3, 4, 1); # Not right in Ruby or Raku (in Raku this would
               # try to pass a single argument of type List to foo)
=end code

=for code :preamble<sub foo($,$,$) {...}>
foo(3, 4, 1);  # Ruby and Raku
foo 3, 4, 1;   # Ruby and Raku - alternative parentheses-less style

=end item

=begin item
I<Space is B<required> immediately after keywords>
=end item

=begin code :lang<ruby>
if(a < 0); ...; end         # OK in Ruby
=end code
=begin code
my $a; ...;
if ($a < 0) { ... }         # Raku
if $a < 0 { ... }           # Raku, more idiomatic
=end code

=begin code :lang<ruby>
while(x > 5); ...; end      # OK in Ruby
=end code
=begin code
my $x; ...;
while ($x > 5) { ... }      # Raku
while $x > 5 { ... }        # Raku, more idiomatic
=end code


=begin item
I<No space allowed before a postfix/postcircumfix operator (including
array/hash subscripts).>

=for code :lang<ruby>
seen [ :fish ] = 1    # Ruby, not idiomatic but allowed

=for code :preamble<my %seen>
%seen< fish > = 1;    # Raku, no space allowed after 'seen'
=end item

=begin item
I<Space required before an infix operator if it would
conflict with an existing postfix/postcircumfix operator.>

=for code :lang<ruby>
n<1     # Ruby (in Raku this would conflict with postcircumfix < >)
=for code :preamble<my $n>
$n < 1; # Raku

=end item

=head2 C«.» Method calls, C<.public_send>

Method call syntax uses a dot just like Ruby:

=for code :lang<ruby>
person.name    # Ruby
=for code
my $person; ...;
$person.name   # Raku

To call a method whose name is not known until runtime:

=for code :lang<ruby>
object.public_send(methodname, args);  # Ruby
=for code
my $object; my Str $methodname; my @args; ...;
$object."$methodname"(@args);   # Raku

If you leave out the quotes, then Raku expects C<$methodname> to contain
a C<Method> object, rather than the simple string name of the method.

=head2 Variables, sigils, scope, and common types

In Ruby, variables use sigils primarily to indicate scope. C<$> for global
scope, C<@@> for class scope, C<@> for instance scope, and no sigil for local
variables (including parameters). The C<&> sigil is also used to indicate
method references. Symbols are prefixed with C<:>, but they are not variable
and so not really sigils.

In Raku sigils are primarily used to indicate a role that the contained value
implements, indicating the type (or at least the interface) of the value. The
sigils are invariant, no matter how the variable is being used - you can think
of them as part of the variable's name.

The scope of a variable is instead indicated by the declaration itself (C<my>,
C<has>, C<our>, etc).

=head3 Variable scope

For local variables, Ruby uses implicit variable declaration upon assignment
and limited to the current block. In Ruby the content of an C<if> or C<while>
built-in construct is not a block or scope.

Raku uses explicit scope indicators, and never creates variables implicitly.
Every place you see C<{ ... }> is a scope, including the body of a conditional
or loop. The commonly used scope declarations:

=for code :lang<ruby>
foo = 7        # Ruby, variable scope is defined by first assignment and
               # extends to the end of the current block

=for code
my  $foo = 7;   # Raku, lexical scoped to the current block
our $foo = 7;   # Raku, package scoped
has $!foo = 7;  # Raku, instance scoped (attribute)

=head3 C<$> Scalar

The C<$> sigil is always used with "scalar" variables (e.g. C<$name>). These
are single-value containers.

This is the most general-purpose variable type, with no restrictions on its
contents. Note that you can still address/use its contents, like C<$x[1]>,
C<$x{"foo"}>, and C<$f("foo")>.

=head3 C<@> Array

The C<@> sigil is always used with "array" variables (e.g. C<@months>,
C<@months[2]>, C<@months[2, 4]> for an array slice). Variables using the C<@>
sigil can only contain things that do the C<Positional> role, indicating
positional indexing and slicing capabilities.

=begin item
I<Indexing>

=for code :lang<ruby>
puts months[2]; # Ruby
=for code :preamble<my @months>
say @months[2]; # Raku
=end item

=begin item
I<Value-slicing>

=for code :lang<ruby>
puts months[8..11].join(',') # Ruby
=for code :preamble<my @months>
say @months[8..11].join(',') # Raku
=end item


=head3 C<%> Hash

The C<%> sigil is always used with "hash" variables (e.g. C<%calories>,
C<%calories<apple>>, C<%calories<pear plum>>). Variables using the C<%> sigil
can only contain things that do the C<Associative> role.

Ruby uses square brackets to access values for both Arrays and Hashes. Raku
uses curly braces for hashes instead. The angle brackets version is available
which always autoquotes its contents (strings without quotes):

Adverbs can be used to control the type of slice.

=begin item
I<Indexing>

=for code :lang<ruby>
puts calories["apple"]  # Ruby
=for code :preamble<my %calories>
say %calories{"apple"}; # Raku

=for code :lang<ruby>
puts calories["apple"]  # Ruby
puts calories[:apple]   # Ruby, symbols for keys are common
=for code :preamble<my %calories; my $key>
say %calories<apple>;   # Raku - angle brackets instead of single-quotes
say %calories«"$key"»;  # Raku - double angles interpolate as double-quotes
=end item

=begin item
I<Value-slicing>

=for code :lang<ruby>
puts calories.values_at('pear', 'plum').join(',') # Ruby
puts calories.values_at(%w(pear plum)).join(',')  # Ruby, pretty?
=for code :preamble<my %calories; my $keys>
say %calories{'pear', 'plum'}.join(',');          # Raku
say %calories<pear plum>.join(',');               # Raku (prettier)
my $keys = 'pear plum';
say %calories« $keys ».join(','); # Raku, interpolated split
=end item

=begin item
I<Key/value-slicing>

=for code :lang<ruby>
puts calories.slice('pear', 'plum')  # Ruby >= 2.5
=for code :preamble<my %calories>
say %calories{'pear', 'plum'}:kv.Hash;   # Raku - use :kv adverb
say %calories<pear plum>:kv.Hash;        # Raku (prettier version)
=end item

=head3 C<&> Sub

The C<&> sigil is used very similarly to Ruby's C<&> to refer to the function
object of a named subroutine/operator without invoking it, i.e. to use the name
as a "noun" instead of a "verb". Variables using the C<&> sigil can only
contain things that do the C<Callable> role.

=begin code :lang<ruby>
add = -> n, m { n + m } # Ruby lambda for an addition function
add.(2, 3)              # => 5, Ruby invocation of a lambda
add.call(2, 3)          # => 5, Ruby invocation of a lambda
=end code

=begin code
my &add = -> $n, $m { $n + $m }; # Raku addition function
&add(2, 3);                      # => 5, you can keep the sigil
add(2, 3);                       # => 5, and it works without it
=end code

=for code :lang<ruby>
def foo
  ...
end
foo_method = method(:foo);     # Ruby
=for code
sub foo { ... };
my &foo_method = &foo; # Raku

=for code :lang<ruby>
some_func(&say) # Ruby pass a function reference
=for code
sub some_func { ... };
some_func(&say) # Raku passes function references the same way

Often in Ruby we pass a block as the last parameter, which is especially used
for DSLs. This can be an implicit parameter called by C<yield>, or an explicit
block prefixed with C<&>. In Raku a C<Callable> parameter is always listed
and called by the variable name (instead of yield), and there are a variety of
ways of invoking the function.

=begin code :lang<ruby>
# Ruby, declare a method and call the implicit block argument
def f
  yield 2
end

# Ruby, invoke f, pass it a block with 1 argument
f do |n|
  puts "Hi #{n}"
end
=end code

=begin code
# Raku, declare a method with an explicit block argument
sub f(&g:($)) {
  g(2)
}

# Raku, invoke f, pass it a block with 1 argument
# There are several other ways to do this
f(-> $n { say "Hi {$n}" }); # Explicit argument
f -> $n { say "Hi {$n}" };  # Explicit argument, no parenthesis

# Additionally, if 'f' is a method on instance 'obj' you can use ':'
# instead of parenthesis
my $obj; ...;
$obj.f(-> $n { say "Hi {$n}" });  # Explicit argument
$obj.f: -> $n { say "Hi {$n}" };  # Explicit argument, no parenthesis
=end code

=head3 C<*> Slurpy params / argument expansion

In Ruby you can declare an argument to slurp the remainder of the passed
parameters into an array using a C<*> prefix. It works similarly in Raku:

=for code :lang<ruby>
def foo(*args); puts "I got #{args.length} args!"; end # Ruby
=for code
sub foo(*@args) { say "I got #{@args.elems} args!" }   # Raku

The Raku version above is slightly different in that when it slurps in the
arguments into @args, one level of nesting, if any, is automatically removed:

=for code
sub foo(*@args) { say @args.raku }
foo([1, [2, 3], 4], 5, [6, 7]);   # [1, [2, 3], 4, 5, 6, 7]

To preserve the structure of the arguments, you can use C<**>:

=for code
sub foo(**@args) { say @args.raku }
foo([1, [2, 3], 4], 5, [6, 7]);  # [[1, [2, 3], 4], 5, [6, 7]]

You might want to expand an array into a set of arguments. In Raku this is
done using a L<Slip|/type/Slip> C<|>:

=for code :lang<ruby>
args = %w(a b c)         # Ruby
foo(*args)

=for code
sub foo($q, $r, $s) { ... };
my @args = <a b c>;       # Raku
foo(|@args);

Raku has many more advanced ways of passing parameters and receiving
arguments, see L<Signatures|/language/functions#Signatures> and
L<Captures|/type/Capture>.

=head2 Twigils

Raku additionally uses "twigils", which are further indicators about the
variable and go between the sigil and the rest of the variable name. Examples:

=begin table
Variable | Description
=========|============
$foo     | Scalar with no twigil
$!foo    | Private instance variable
$.foo    | Instance variable accessor
$*foo    | Dynamically scoped variable
$^foo    | A positional (placeholder) parameter to a block
$:foo    | A named (placeholder) parameter to a block
$=foo    | POD (documentation) variables
$?FILE   | Current source filename. The ? twigil indicates a compile-time value
$~foo    | Sublanguage seen by parser, uncommon
=end table

Though each of these examples use the C<$> sigil, most could use C<@>
(Positional) or C<%> (Associative).

=head2 C<:> Symbols

Raku generally uses strings in the places where Ruby uses symbols. A primary
example of this is in hash keys.

=for code :lang<ruby>
address[:joe][:street] # Typical Ruby nested hash with symbol keys
=for code
my %address; ...;
%address<joe><street>  # Typical Raku nested hash with string keys

Raku has I<colon-pair> syntax, which can sometimes look like Ruby symbols.

=for code :lang<ruby>
:age            # Ruby symbol

=begin code
# All of these are equivalent for Raku
:age            ;# Raku pair with implicit True value
:age(True)      ;# Raku pair with explicit True value
age => True     ;# Raku pair using arrow notation
"age" => True   ;# Raku pair using arrow notation and explicit quotes
=end code

You could probably get away with using a colon-pair without an explicit value
and pretend that it is a Ruby symbol a lot of the time, but it isn't idiomatic
Raku.

=head1 Operators

Many operators have a similar usage in both Ruby and Raku:

=item C<,> List Separator
=item C<+> Numeric Addition
=item C<-> Numeric Subtraction
=item C<*> Numeric Multiplication
=item C</> Numeric Division
=item C<%> Numeric Modulus
=item C<**> Numeric Exponentiation
=item C<! && ||> Booleans, high-precedence
=item C<not and or> Booleans, low-precedence

You may use C<$x++> instead of C<x += 1> as a shortcut for incrementing a
variable. This can be used as a pre-increment C<++$x> (increment, return new
value) or post-increment C<$x++> (increment, return old value).

You may use C<$x--> instead of C<x -= 1> as a shortcut for decrementing a
variable. This can be used as a pre-decrement C<--$x> (decrement, return new
value) or post-decrement C<$x--> (decrement, return old value).

=head2 C«== != < > <= >=» Comparisons

Comparisons in Raku are separated between numeric and string to avoid common
errors.

=item C«== != < > <= >=» Comparisons
=item C<eq ne lt gt le ge> String comparisons

For example, using C<==> tries to convert the values to numbers, and C<eq>
tries to convert the values to strings.

=head2 C«<=>» Three-way comparisons

In Ruby, the C«<=>» operator returns -1, 0, or 1.
In Raku, they return C<Order::Less>, C<Order::Same>, or C<Order::More>.

C«<=>» forces numeric context for the comparison.

C«leg» ("Less, Equal, or Greater?") forces string context for the comparison.

C«cmp» does either C«<=>» or C<leg>, depending on the existing type of its
arguments.

=head2 C<~~> Smartmatch operator

This is a very common matching operator which is similar to C<===> in Ruby. Here are
some examples:

    my $foo; ...;
    say "match!" if $foo ~~ /bar/;       # Regex match
    say "match!" if $foo ~~ "bar";       # String match
    say "match!" if $foo ~~ :(Int, Str); # Signature match (destructure)

An equivalent in Ruby would be

=for code :lang<ruby>
$foo = 'bar';
puts "match 1!" if /bar/ === $foo;       # Regex match
puts "match 2!" if $foo === "bar";       # String match
puts "match 3!" if String === $foo;      # Class match

Please note that, in this case, C<===> is not symmetric; in the first
and last case, the variable has to be in the right-hand side. There is
no equivalent to the signature class in Ruby, either.

See L<S03/Smartmatching|https://design.raku.org/S03.html#Smart_matching> for more information on this feature.

=head2 C<& | ^> Numeric bitwise ops
=head2 C<& | ^> Boolean ops

In Raku, these single-character ops have been removed, and replaced by
two-character ops which coerce their arguments to the needed context.

=begin code :lang<text>
# Infix ops (two arguments; one on each side of the op)
+&  +|  +^  And Or Xor: Numeric
~&  ~|  ~^  And Or Xor: String
?&  ?|  ?^  And Or Xor: Boolean

# Prefix ops (one argument, after the op)
+^  Not: Numeric
~^  Not: String
?^  Not: Boolean (same as the ! op)
=end code

=head2 C<&.> Conditional chaining operator

Ruby uses the C<&.> operator to chain methods without raising an error if one
invocation returns nil. In Raku use C<.?> for the same purpose.

=head2 C«<< >>» Numeric shift left, right ops, shovel operator

Replaced by C«+<» and C«+>» .

=for code :lang<ruby>
puts 42 << 3  # Ruby
=for code
say  42 +< 3; # Raku

Note that Ruby often uses the C«<<» operator as the "shovel operator", which is
similar to C<.push>. This usage isn't common in Raku.

=head2 C«=>» and C<:> Key-value separators

In Ruby, C«=>» is used in the context of key/value pairs for Hash literal
declaration and parameter passing. C<:> is used as a shorthand when the left
side is a symbol.

In Raku, C«=>» is the Pair operator, which is quite different in
principle, but works the same in many situations.

If you are using C«=>» in a hash literal, then the usage is very similar:

=for code :lang<ruby>
hash = { "AAA" => 1, "BBB" => 2 }  # Ruby, though symbol keys are more common
=for code
my %hash = ( AAA => 1, BBB => 2 ); # Raku, uses ()'s though {} usually work

=head2 C<? :> Ternary operator

In Raku, this is spelled with two question marks instead of one question
mark, and two exclamation points instead of one colon. This deviation from the
common ternary operators disambiguates several situations and makes the
false-case stand out more.

=for code :lang<ruby>
result     = (  score > 60 )  ? 'Pass'  : 'Fail'; # Ruby
=for code
my $score; ...;
my $result = ( $score > 60 ) ?? 'Pass' !! 'Fail'; # Raku

=head2 C<+> String concatenation

Replaced by the tilde. Mnemonic: think of "stitching" together the two strings with needle and thread.

=for code :lang<ruby>
$food = 'grape' + 'fruit'  # Ruby
=for code
my $food = 'grape' ~ 'fruit'; # Raku

=head2 String interpolation

In Ruby, C<"#{foo}s"> deliminates a block embedded in a double-quoted string.
In Raku drop the C<#> prefix: C<"{$foo}s">. As in Ruby, you can place
arbitrary code into the embedded block and it will be rendered in string
context.

Simple variables can be interpolated into a double-quoted string without using the block syntax:

=begin code :lang<ruby>
# Ruby
name = "Bob"
puts "Hello! My name is #{name}!"
=end code

=begin code :lang<ruby>
# Raku
my $name = "Bob";
say "Hello! My name is $name!"
=end code

The result of an embedded block in Ruby uses C<.to_s> to get string context.
Raku uses C<.Str>, or C<.gist> for the same affect.

=head1 Compound statements

=head2 Conditionals

=head3 C<if> C<elsif> C<else> C<unless>

This work very similarly between Ruby and Raku, but Raku uses C<{ }> to
clearly delineate the blocks.

=begin code :lang<ruby>
# Ruby
if x > 5
    puts "Bigger!"
elsif x == 5
    puts "The same!"
else
    puts "Smaller!"
end
=end code

=begin code
# Raku
my $x; ...;
if $x > 5 {
    say "Bigger!"
} elsif $x == 5 {
    say "The same!"
} else {
    say "Smaller!"
}
=end code

Binding the conditional expression to a variable is a little different:

=for code :lang<ruby>
if x = dostuff(); ...; end   # Ruby
=for code
sub dostuff() {...};
if dostuff() -> $x {...}     # Raku, block-assignment uses arrow

The C<unless> conditional only allows for a single block in Raku;
it does not allow for an C<elsif> or C<else> clause.

=head3 C<case>-C<when>

The Raku C<given>-C<when> construct is like a chain of C<if>-C<elsif>-C<else>
statements, and its direct analog is Ruby's C<case>-C<when> construct.
Just as Ruby uses the C<===> (case equality) operator for each condition in a
C<case>-C<when> expression, Raku, likewise, uses the smartmatch C<~~> operator
with C<given>-C<when>.

It has the
general structure:

=begin code :lang<pseudo>
given EXPR {
    when EXPR { ... }
    when EXPR { ... }
    default { ... }
}
=end code

In its simplest form, the construct is as follows:

    my $value; ...;
    given $value {
        when "a match" {
            # do-something();
        }
        when "another match" {
            # do-something-else();
        }
        default {
            # do-default-thing();
        }
    }

This is simple in the sense that a scalar value is matched in the C<when>
statements. More generally, the matches are actually smartmatches on the
input value such that lookups using more complex entities such as regexps
can be used instead of scalar values.

=head2 Loops

=head3 C<while> C<until>

Mostly unchanged; parentheses around the conditions are optional, but if used, must
not immediately follow the keyword, or it will be taken as a function call
instead. Binding the conditional expression to a variable is also a little
different:

=for code :lang<ruby>
while x = dostuff(); ...; end    # Ruby
=for code
sub dostuff {...}; ...;
while dostuff() -> $x {...}      # Raku

=head3 C<for> C<.each>

C<for> loops are rare in Ruby, instead we typically use C<.each> on an
enumerable. The most direct translation to Raku would be to use C<.map> for
both C<.each> and C<.map>, but we typically use a C<for> loop directly.

=begin code :lang<ruby>
# Ruby for loop
for n in 0..5
    puts "n: #{n}"
end

# Ruby, more common usage of .each
(0..5).each do |n|
    puts "n: #{n}"
end
=end code

=begin code
# Raku
for 0..5 -> $n {
    say "n: $n";
}

# Raku, misusing .map
(0..5).map: -> $n {
    say "n: $n";
}
=end code

In Ruby, the iteration variable for C<.each> is a copy of the list element, and
modifying it does nothing to the original list. Note that it is a copy of the
REFERENCE, so you can still change the values to which it refers.

In Raku, that alias is read-only (for safety) and thus behaves exactly like
Ruby, unless you change C«->» to C«<->».

=for code :lang<ruby>
cars.each { |car| ... }    # Ruby; read-only reference
=for code
my @cars; ...;
for @cars  -> $car   {...} # Raku; read-only
for @cars <-> $car   {...} # Raku; read-write

=head2 Flow interruption statements

Same as Ruby:

=item C<next>
=item C<redo>

=item2 C<break>

This is C<last> in Raku.

=head1 Regular expressions ( regex / regexp )

Regular expressions in Raku are significantly different, and more powerful,
than in Ruby. By default whitespace is ignored and all characters must be
escaped, for example. Regexes can be easily combined and declared in ways to
build efficient grammars.

There are many powerful features of Raku regexes, especially defining entire
grammars using the same syntax. See L<Regexes|/language/regexes> and
L<Grammars|/language/grammars>.

=head2 C<.match> method and C<=~> operator

In Ruby, regex matches can be done against a variable using the C<=~> regexp
match operator or the C<.match> method. In Raku, the C<~~> smartmatch op is
used instead, or the C<.match> method.

=for code :lang<ruby>
next if line   =~ /static/   # Ruby
next if line  !~  /dynamic/; # Ruby
next if line.match(/static/) # Ruby

=for code
my $line; ...;
next if $line  ~~ /static/;    # Raku
next if $line !~~ /dynamic/ ;  # Raku
next if $line.match(/static/); # Raku

Alternately, the C<.match> and C<.subst> methods can be used. Note that
C<.subst> is non-mutating. See
L<S05/Substitution|https://design.raku.org/S05.html#Substitution>.

=head2 C<.sub> and C<.sub!>

In Raku you typically use the C<s///> operator to do regex substitution.

=for code :lang<ruby>
fixed = line.sub(/foo/, 'bar')        # Ruby, non-mutating
=for code
my $line; ...;
my $fixed = $line.subst(/foo/, 'bar') # Raku, non-mutating

=for code :lang<ruby>
line.sub!(/foo/, 'bar')   # Ruby, mutating
=for code
my $line; ...;
$line ~~ s/foo/bar/;      # Raku, mutating

=head2 Regex options

Move any options from the end of the regex to the beginning. This may
require you to add the optional C<m> on a plain match like C«/abc/».

=for code :lang<ruby>
next if $line =~    /static/i # Ruby
=for code
my $line; ...;
next if $line ~~ m:i/static/; # Raku

=head2 Whitespace is ignored, most things must be quoted

In order to aid in readability and reusability, whitespace is not significant
in Raku regexes.

=for code :lang<ruby>
/this is a test/ # Ruby, boring string
/this.*/         # Ruby, possibly interesting string

=for code
/ this " " is " " a " " test /; # Raku, each space is quoted
/ "this is a test" /;           # Raku, quoting the whole string
/ this .* /;                    # Raku, possibly interesting string

=head2 Special matchers generally fall under the <> syntax

There are many cases of special matching syntax that Raku regexes support.
They won't all be listed here, but often instead of being surrounded by C<()>,
the assertions will be surrounded by C«<>».

For character classes, this means that:

=item C<[abc]> becomes C«<[abc]>»

=item C<[^abc]> becomes C«<-[abc]>»

=item C<[a-zA-Z]> becomes C«<[a..zA..Z]>»

=item C<[[:upper:]]> becomes C«<:upper>»

=item C<[abc[:upper:]]> becomes C«<[abc]+:Upper>»

For look-around assertions:

=item C<(?=[abc])> becomes C«<?[abc]>»

=item C<(?=ar?bitrary* pattern)> becomes C«<before ar?bitrary* pattern>»

=item C<(?!=[abc])> becomes C«<![abc]>»

=item C<(?!=ar?bitrary* pattern)> becomes C«<!before ar?bitrary* pattern>»

=item C«(?<=ar?bitrary* pattern)» becomes C«<after ar?bitrary* pattern>»

=item C«(?<!ar?bitrary* pattern)» becomes C«<!after ar?bitrary* pattern>»

(Unrelated to <> syntax, the "lookaround" C</foo\Kbar/> becomes C«/foo <( bar )> /»

=item C<(?(?{condition))yes-pattern|no-pattern)> becomes C«[ <?{condition}>
      yes-pattern | no-pattern ]»

=head2 Longest token matching (LTM) displaces alternation

In Raku regexes, C<|> does Longest Token Match (LTM), which decides which
alternation wins an ambiguous match based off of a set of rules, rather than
about which was written first in the regex.

To avoid the new logic, change any C<|> in your Ruby regex to a C<||>.

=head1 File-related operations

=head2 Reading the lines of a text file into an array

Both Ruby and Raku make it easy to read all of the lines in a file into a
single variable, and in both cases each line has the newline removed.

=for code :lang<ruby>
lines = File.readlines("file")   # Ruby
=for code
my @lines = "file".IO.lines;     # Raku, create an IO object from a string

=head2 Iterating over the lines of a text file

Reading the entire file into memory isn't recommended. The C<.lines> method in
Raku returns a lazy sequence, but assigning to an array forces the file to be
read. It is better to iterate over the results:

=begin code :lang<ruby>
# Ruby
File.foreach("file") do |line|
    puts line
end
=end code

=begin code
# Raku
for "file".IO.lines -> $line {
    say $line
}
=end code

=head1 Object orientation

=head2 Basic classes, methods, attributes

Classes are defined similarly between Ruby and Raku, using the C<class>
keyword. Ruby uses C<def> for methods, whereas Raku uses C<method>.

=begin code :lang<ruby>
# Ruby
class Foo
    def greet(name)
        puts "Hi #{name}!"
    end
end
=end code

=begin code
# Raku
class Foo {
    method greet($name) {
        say "Hi $name!"
    }
}
=end code

In Ruby you can use an attribute without declaring it beforehand, and you can
tell it is an attribute because of the C<@> sigil. You can also easily create
accessors using C<attr_accessor> and its variants. In Raku you use a C<has>
declaration and a variety of sigils. You can use the C<!> twigil for private
attributes or C<.> to create an accessor.

=begin code :lang<ruby>
# Ruby
class Person
    attr_accessor :age    # Declare .age as an accessor method for @age
    def initialize
        @name = 'default' # Assign default value to private instance var
    end
end
=end code

=begin code
# Raku
class Person {
    has $.age;              # Declare $!age and accessor methods
    has $!name = 'default'; # Assign default value to private instance var
}
=end code

Creating a new instance of the class uses the C<.new> method. In Ruby you must
manually assign instance variables as needed inside C<initialize>. In Raku
you get a default constructor that accepts key/value pairs of accessor
attributes, and can do further setup in the C<TWEAK> method. Like with Ruby,
you can override C<new> itself for more advanced functionality, but this is
rare.

=begin code :lang<ruby>
# Ruby
class Person
    attr_accessor :name, :age
    def initialize(attrs)
        @name = attrs[:name] || 'Jill'
        @age  = attrs[:age] || 42
        @birth_year = Time.now.year - @age
    end
end
p = Person.new( name: 'Jack', age: 23 )
=end code

=begin code
# Raku
class Person {
    has $.name = 'Jill';
    has $.age  = 42;
    has $.birth_year;
    method TWEAK {
        $!birth_year = now.Date.year - $!age;
    }
}
my $p = Person.new( name => 'Jack', age => 23 )
=end code

=head2 Private methods

Private methods in Raku are declared with a C<!> prefixed in their name, and
are invoked with a C<!> instead of a C<.>.

=begin code :lang<ruby>
# Ruby
class Foo
    def visible
        puts "I can be seen!"
        hidden
    end

    private
    def hidden
        puts "I cannot easily be called!"
    end
end
=end code

=begin code
# Raku
class Foo {
    method visible {
        say "I can be seen!";
        self!hidden;
    }

    method !hidden {
        say "I cannot easily be called!";
    }
}
=end code

An important note is that in Ruby child objects can see parent private methods
(so they are more like "protected" methods in other languages). In Raku child
objects cannot call parent private methods.

=head2 Going I<meta>

Here are a few examples of metaprogramming. Note that Raku separates the
metamethods from the regular methods with a caret.

=for code :lang<ruby>
# Ruby
person = Person.new
person.class
person.methods
person.instance_variables

=for code
# Raku
class Person {};
...
my $person = Person.new;
$person.^name;             # Raku, returns Person (class)
$person.^methods;          # Raku, using .^ syntax to access metamethods
$person.^attributes;


Like Ruby, in Raku, everything is an object, but not all operations are
equivalent to C<.public_send>. Many operators are global functions that use typed
multi-dispatch (function signatures with types) to decide which implementation
to use.

=for code :lang<ruby>
5.public_send(:+, 3)    # => 8, Ruby
=for code
&[+](5, 3)       # => 8, Raku, reference to infix addition operator
&[+].^candidates # Raku, lists all signatures for the + operator

See L<Metaobject Protocol|/language/mop> for lots of further details.

=head1 Environment variables

=head2 Raku module library path

In Ruby, one of the environment variables to specify extra search paths for
modules is C<RUBYLIB>.

=for code :lang<shell>
$ RUBYLIB="/some/module/lib" ruby program.rb

In Raku this is similar, you merely needs to change the name. As you probably
guessed, you just need to use C<RAKULIB>:

=for code :lang<shell>
$ RAKULIB="/some/module/lib" raku program.raku

As with Ruby, if you don't specify C<RAKULIB>, you need to specify the
library path within the program via the C<use lib> pragma:

=for code :solo
# Ruby and Raku
use lib '/some/module/lib';

=head1 Misc.

=head2 Importing specific functions from a module

In Ruby there is no built-in way to selectively import/export methods from a
module.

In Raku you specify the functions which are to be exported by using the
C<is export> role on the relevant subs and I<all> subs with this role are
then exported. Hence, the following module C<Bar> exports the subs C<foo>
and C<bar> but not C<baz>:

=for code :solo
unit module Bar; # remainder of the file is in module Bar { ... }
sub foo($a) is export { say "foo $a" }
sub bar($b) is export { say "bar $b" }
sub baz($z) { say "baz $z" }

To use this module, simply C<use Bar> and the functions C<foo> and C<bar>
will be available:

=for code :skip-test<needs dummy module>
use Bar;
foo(1);    #=> "foo 1"
bar(2);    #=> "bar 2"

If you try to use C<baz> an "Undeclared routine" error is raised at compile time.

Some modules allow for selectively importing functions, which would look like:

=begin code :skip-test<needs dummy module>
use Bar <foo>; # Import only foo
foo(1);        #=> "foo 1"
bar(2);        # Error!
=end code

=head2 C<OptionParser>, parsing command-line flags

Command line argument switch parsing in Raku is done by the parameter list of
the C<MAIN> subroutine.

=begin code :lang<ruby>
# Ruby
require 'optparse'
options = {}
OptionParser.new do |opts|
    opts.banner = 'Usage: example.rb --length=abc'
    opts.on("--length", "Set the file") do |length|
        raise "Length must be > 0" unless length.to_i > 0
        options[:length] = length
    end
    opts.on("--filename", "Set the file") do |filename|
        options[:file] = filename
    end
    opts.on("--verbose", "Increase verbosity") do |verbose|
        options[:verbose] = true
    end
end.parse!

puts options[:length]
puts options[:filename]
puts 'Verbosity ', (options[:verbose] ? 'on' : 'off')
=end code

=begin code :lang<shell>
ruby example.rb --filename=foo --length=42 --verbose
    42
    foo
    Verbosity on

ruby example.rb --length=abc
    Length must be > 0
=end code

=begin code
# Raku
sub MAIN ( Int :$length where * > 0, :$filename = 'file.dat', Bool :$verbose ) {
    say $length;
    say $filename;
    say 'Verbosity ', ($verbose ?? 'on' !! 'off');
}
=end code

=begin code :lang<shell>
raku example.p6 --file=foo --length=42 --verbose
    42
    foo
    Verbosity on
raku example.p6 --length=abc
    Usage:
      example.p6 [--length=<Int>] [--file=<Any>] [--verbose]
=end code

Note that Raku auto-generates a full usage message on error in
command-line parsing.

=head1 RubyGems, external libraries

See L<https://modules.raku.org/>, where a growing number of Raku libraries
are available along with the tools to manage them.

If the module that you were using has not been converted to Raku, and no
alternative is listed in this document, then its use under Raku may not
have been addressed yet.

You can experiment with L<Inline::Ruby|https://modules.raku.org/dist/Inline::Ruby:github:github:awwaiid>
to call existing Ruby code from your Raku programs. This uses an embedded
instance of the C<ruby> interpreter to run Ruby code called from your Raku
script. Note that this is an EXPERIMENTAL library. You can similarly call other
language's libraries with Inline::Perl5, Inline::Python, and others.

=begin comment

### Guidelines for contributions:

Headers should contain the text that a Ruby user might search for, since
those headings will be in the Table of Contents generated for the top of
the document.

We use POD =item instead of =head3 or =head4 for identical bits that need not
appear in the table of contents.

This article does not describe in detail language features that Ruby doesn't
have at all, instead referring to other documents.

Example code and links to other documents should be favored over long
explanations of details better found elsewhere.

Finally, if a real user asks a Ruby to Raku question that is not being
answered here, please add it to the document. Even if we do not have a good
answer yet, that will be better than losing the information about a real need.

=end comment

=end pod


# vim: expandtab softtabstop=4 shiftwidth=4 ft=perl6
